Meeting Pearls 1

home *** CD-ROM | disk | FTP | other *** search

/ Meeting Pearls 1 / Meeting Pearls Vol 1 (1994).iso / installed_progs / gfx / daggex / docs / clients / xv.doc < prev

Wrap

Text File | 1994-06-04 | 132.2 KB | 3,234 lines

Feb 26, 1992 xv(l) NAME xv - interactive image display for the X Window System SYNTAX xv [_o_p_t_i_o_n_s] [_f_i_l_e_n_a_m_e [_f_i_l_e_n_a_m_e...]] NOTE This man page is merely the text portion of the (PostScript) _x_v docs, without the figures, and without the appendicies. As such, it is highly recommended that you get your hands on the *real* documentation. DESCRIPTION _x_v is an X11 program that displays images in the GIF, JPEG, TIFF, PBM, PGM, PPM, X11 bitmap, Utah Raster Toolkit RLE, PDS/VICAR, Sun Raster- file, and PM formats on 1-, 2-, 4-, 6-, 8-, 16-, 24-, and 32-bit X displays. _x_v will also read _c_o_m_p_r_e_s_s-ed versions of these files. SECTION 1: OVERVIEW _x_v version 2.10 lets you do a large number of things (many of them actu- ally useful), including, but not limited to, the following: o+ display an image in a window on the screen o+ display an image on the root window, in a variety of styles o+ grab any rectangular portion of the screen and turn it into an image o+ arbitrarily stretch or compress the image o+ rotate the image in 90-degree steps o+ flip the image around the horizontal or vertical axes o+ crop a rectangular portion of the image o+ magnify any portion of the image by any amount, up to the size of the screen o+ determine pixel values and x,y coordinates in the image o+ adjust image brightness and contrast with a gamma correction function o+ apply different gamma functions to the Red, Green, and Blue color components, to correct for non-linear color response o+ adjust global image saturation o+ perform global hue remapping o+ perform histogram equalization Rev: 2.10 1 xv(l) Feb 26, 1992 o+ edit an image's colormap o+ reduce the number of colors in an image o+ dither in color and b&w o+ smooth an image o+ crop off solid borders automatically o+ convert image formats o+ generate Encapsulated PostScript Unfortunately the _A_u_t_o_m_a_t_i_c _C_h_e_c_k_b_o_o_k _B_a_l_a_n_c_i_n_g _M_o_d_u_l_e still isn't com- pletely debugged, and is not included in this distribution. SECTION 2: STARTING XV Note: unless explicitly stated otherwise, the term _c_l_i_c_k means "click with the _L_e_f_t mouse button." Start the program up by typing 'xv'. After a short delay, a window will appear with the default image (the _x_v logo, credits and revision date) displayed in it. If you change the size of the window (using whatever method your window manager provides), the image will be automatically stretched to fit the window. Section 2.1: Displaying Pixel Values Clicking (and optionally dragging) the _L_e_f_t mouse button inside this window will display pixel information in the following format: 196, 137 = 191,121,209 (287 42 81 HSV) The first pair of numbers (196,137) are the x and y positions of the cursor, in image coordinates. These numbers remain the same regardless of any image resizing, or cropping. For example, if you click on the eye of the fish on the right side of the default image, you'll get (approximately) 251,129 regardless of the size of the displayed image. This allows you to zoom in for precise measurements. The first triplet of numbers (191,121,209) are the RGB values of the selected pixel. The components will have integer values in the range 0-255. The values displayed are prior to any HSV/RGB modification, but after any colormap changes. See "Section 5: The Color Editor" for details. The second triplet of numbers (287 42 81) are the HSV values of the selected pixel. The first component will have integer values in the range 0-359, and the second and third components will have integer 2 Rev: 2.10 Feb 26, 1992 xv(l) values in the range 0-100. The values displayed are prior to any HSV/RGB modification, but after any colormap changes. See "Section 5: The Color Editor" for details. Also, see "Appendix D: RGB and HSV Colorspaces" for more information about what these numbers mean. Note: If you actually want to measure some pixels, it will probably help to crop to a small region of your image, and expand that region to the point where you can see the individual pixels. This string is automatically copied to your X server's cut buffer when- ever you measure pixel values. This lets you easily feed this informa- tion to another program, useful if you're doing manual feature extrac- tion, or something. Try it: measure a pixel's value, and then go click your _M_i_d_d_l_e mouse button in an _x_t_e_r_m window. Section 2.2: Cropping Bring up the _x_v _c_o_n_t_r_o_l_s window by typing the '?' key or clicking the _R_i_g_h_t mouse button inside the image window. Clicking and dragging the _M_i_d_d_l_e button of the mouse inside the image window will allow you to draw a cropping rectangle on the image. If you're unhappy with the one you've drawn, simply click the _M_i_d_d_l_e button and draw another. If you'd like the rectangle to go away altogether, click the _M_i_d_d_l_e button and release it without moving the mouse. You can determine how large the cropping rectangle is (in image coordi- nates) by bringing up the _x_v _i_n_f_o window. Do this by clicking the Info button in the _x_v _c_o_n_t_r_o_l_s _w_i_n_d_o_w or by typing the 'i' key into any open _x_v window. The _x_v _i_n_f_o _w_i_n_d_o_w will display, among other things, the current size and position of the cropping rectangle in terms of image coordinates. For example, if it says: 114x77 rectangle starting at 119,58 that would mean that the current cropping rectangle is 114 image pixels wide, 77 image pixels high, and its top-left corner is located 119 image pixels in from the left edge of the image, and 58 image pixels in from the top edge. These values will be updated as you drag the cropping rectangle around. If you want to set the size or position of the cropping rectangle pre- cisely, you can use the arrow keys on your keyboard. First, make the _x_v _i_n_f_o window visible as described above (if it's not already visible). Second, use the mouse to draw a rough approximation of the cropping rec- tangle that you want. You can now use the arrow keys to move the crop- ping rectangle around the image. Once you've gotten the top and left sides of the cropping rectangle precisely where you want them, you can move the bottom-right corner of the cropping rectangle (only) by holding the <shift> key down while using the arrow keys. Pressing the up arrow Rev: 2.10 3 xv(l) Feb 26, 1992 will make the rectangle shorter, and pressing the down arrow will make the rectangle taller. Once you have a cropping rectangle that you can live with, you can proceed with the actual cropping operation. Click the Crop button in the _x_v _c_o_n_t_r_o_l_s window, or type the 'c' key in any open _x_v window. The image window will shrink to show only portions of the image that were inside the cropping rectangle. Note: if you are running a window manager such as _m_w_m, which decorates windows with a title bar, resizing regions, and such, it is quite possi- ble that the aspect ratio of the cropped image will get screwed up. This is because certain window managers enforce a minimum window size. If you try to crop to a rectangle that is too small, the window manager will create the smallest window it can, and the image will be stretched to fit this window. If this happens, you can press the Aspect button in the _x_v _c_o_n_t_r_o_l_s window, or type the 'a' key in any open _x_v window. This will expand the image so that it has the correct aspect ratio again. You can crop a cropped image by repeating the same steps (drawing a new cropping rectangle and issuing the Crop command), ad infinitum. You can return to the original, uncropped image by using the UnCrop com- mand. Simply click the UnCrop button or type the 'u' key in any open _x_v window. Note that using the UnCrop command will turn off image smooth- ing (the Smooth) command), due to the potentially long time it can take to generate a large, smoothed image. Note that if you try to make the cropping rectangle too small in either width or height (under 5 screen pixels), it'll just turn itself off. If you want to crop a very small portion of an image, you'll probably have to do it in two passes. First, crop to a small (but large enough to still be enabled) rectangle, expand that region, then crop again. Section 2.3: Zooming You can zoom in by a factor of two (or four, eight, etc.) on any rec- tangular region of the image by holding down the <ctrl> key on your key- board and clicking the _L_e_f_t mouse button in the image. A rectangle will flash, centered around the cursor position, and the region inside that rectangle will be doubled in size. The image window should remain the same size, and in the same position. You can repeat this operation to zoom in by a factor of four, or eight, or whatever, as many times as you wish. You can zoom out by a factor of two (if possible) by holding down the <ctrl> key on your keyboard and clicking the _R_i_g_h_t mouse button inside the image window. You can not zoom out beyond the point where the entire image fill the window. 4 Rev: 2.10 Feb 26, 1992 xv(l) SECTION 3: THE CONTROL WINDOW The _x_v _c_o_n_t_r_o_l_s window is the central point of control for the program, hence the name. It provides controls to resize the current image, flip and rotate it, load and save different files, and bring up the other _x_v windows. It can be brought up by clicking the _R_i_g_h_t mouse button in the image window, or by typing the '?' key inside any open _x_v window. Doing either of these things while the _x_v _c_o_n_t_r_o_l_s window is visible will hide it. All of the following commands may be executed by either clicking the appropriate command button, or typing the keyboard equivalent (where given) into any open _x_v window. Section 3.1: Resizing Commands Note that none of the 'resizing' commands modify the image in any way. They only affect how the image is displayed. The image remains at its original size. This allows you to arbitrarily stretch and compact the image without compounding error caused by earlier resizing. In each case, the displayed image is recomputed from the original internal image. Normal (Keyboard equivalent 'n') Attempts to return the image to its normal size, where one image pixel maps to one screen pixel. For example, if the image (or the current cropped portion of the image) has a size of 320x200, this command will attempt to make the image window be 320 screen pixels wide by 200 screen pixels high. This command may fail in two cases. If you're running a window manager (such as _m_w_m) that enforces a minimum window size, and the 'normal' size is too small, the image may get distorted. See the note in "Section 2.2: Cropping" for more information. Also, if the image is larger than the size of your screen, it will be 'halved' until it fits on the screen. For example, if you try to display a 1400x900 image on a 1280x1024 screen, the Normal com- mand will display a 700x450 image. Max Size (Keyboard equivalent 'm') This command will make the displayed image be the same size as the screen. If you are running a window manager that puts up a titlebar, you'll find that the titlebar is now off the top of the screen. To get the titlebar back, simply shrink the image to any- thing smaller than the size of the screen. The window will be moved so that the titlebar is once again visible. Maxpect (Keyboard equivalent 'M') Rev: 2.10 5 xv(l) Feb 26, 1992 Makes the image as large as possible, while preserving the aspect ratio. This avoids the generally unwanted image distortion that Max Size is capable of generating. For example, if you have a 320x200 image, and an 1280x1024 screen, doing the Maxpect command will result in an image that is 1280x800. Max Size, on the other hand, would've generated an image of size 1280x1024, which would be appear 'stretched' vertically. Dbl Size (Keyboard equivalent '>') Doubles the current size of the image, with the constraint that neither axis is allowed to be larger than the screen. For example, given a 320x200 image and a 1280x1024 screen, the image can be dou- bled once (to 640x400), a second time (to 1280x800), but a third time would make the image 1280x1024. You'll note that on the third time, the width didn't change at all, since it was already at its maximum value. Also note that the height wasn't allowed to double (from 800 to 1600), but was truncated at its maximum value (1024). Half Size (Keyboard equivalent '<') Halves the current size of the image, with the constraint that nei- ther axis is allowed to have a size less than 1 pixel. Also, you may run into 'minimum size' problems with your window manager. See the note in "Section 2.2: Cropping" for more information. Note that the window size is maintained as a pair of integers. As a result you may see some integer round-off problems. For example, if you halve a 265x185 image, you'll get a 132x92 image, which is just fine. However, if you Dbl Size this image, you'll get a 264x184 image, not the 265x185 image you might have expected. +10% (Keyboard equivalent '.') Increases the current size of the image by 10%, subject to the con- straint that the image cannot be made larger than the screen size (in either axis). For example, issuing this command on a 320x200 image will result in a 352x220 image. -10% (Keyboard equivalent ',') Decreases the current size of the image by 10%. Neither axis of the image is allowed to shrink below 1 pixel. Also, you run the risk of running into 'minimum window size' problems with your win- dow manager. It should be noted that the +10% and -10% commands have no concept of an 'original size'. They simply increase or decrease the current image size by 10%. As a result, they do not undo each other. For example, take a 320x200 image. Do a +10% and the image will be 352x220. If you issue the -10% command now, the image will be made (352 - 35.2)x(220 - 22), or 316x198. 6 Rev: 2.10 Feb 26, 1992 xv(l) 4x3 (Keyboard equivalent '4') Attempts to resize the image so that the ratio of width to height is equal to 4 to 3. (e.g., 320x240, 400x300, etc.) This is useful because many images were meant to fill the screen of whatever sys- tem they were generated on, and nearly all video tubes have an aspect ratio of 4:3. This command will stretch the image so that things will probably look right on your X display (nearly all of which, thankfully, have square pixels). This command is particu- larly useful for images which have really bizarre sizes (such as the 600x200 images presumably meant for CGA, and the 640x350 16- color EGA images). Aspect (Keyboard equivalent 'a') Applies the 'default aspect ratio' to the image. This is done automatically when the image is first loaded. Normally, the default aspect ratio is '1:1', but certain GIF files may have an aspect ratio encoded in them. You can also set the default aspect ratio via a command-line argument or an X resource. See 'Section 9: Modifying XV Behavior' for more info. The idea behind this com- mand is that you'd stretch the image manually (via your window manager) to roughly the size you'd like, and then use the Aspect command to fix up the proportions. Normally Aspect expands one axis of the image to correct the aspect ratio. If this would result in an image that is larger than the screen, the Aspect command will instead shrink one of the axes to correct the aspect ratio. Section 3.2: Rotate/Flip Commands Turn CW (Keyboard equivalent 't') Rotates the image 90 degrees clockwise. Turn CCW (Keyboard equivalent 'T') Rotates the image 90 degrees counter-clockwise. Flip H (Keyboard equivalent 'h') Flips the image horizontally (around the vertical center-line of the image). Flip V (Keyboard equivalent 'v') Flips the image vertically (around the horizontal center-line of the image). Rev: 2.10 7 xv(l) Feb 26, 1992 Section 3.3: Smoothing Commands Raw (Keyboard equivalent 'r') Returns the displayed image to its 'raw' state (where each pixel in the displayed image is as close as possible to the corresponding pixel in the internal image). In short, it turns off any dithering or smoothing. When dithering or smoothing haven't been done, this command is disabled. Dither (Keyboard equivalent 'd') Regenerates the displayed image by dithering with the available colors in an attempt to approximate the original image. This is only relevant if the color allocation code failed to get all the colors it wanted. If it did get all the desired colors, the Dither command will just generate the same display image as the Raw com- mand. On the other hand, if you didn't get all the desired colors, the Dither command will try to approximate the missing colors by dithering with the colors that were obtained. If you're running _x_v on a 1-bit display the Dither command will be disabled, as the image will always be dithered for display. Smooth (Keyboard equivalent 's') Smooths out distortion caused by integer round-off when an image is expanded or shrunk. This is generally a desirable effect, however it is fairly time-consuming on large images on most current works- tations. As such, by default, it is not done automatically. See "Section 9: Modifying XV Behavior" for more details. Section 3.4: Cropping Commands Crop (Keyboard equivalent 'c') Crops the image to the current cropping rectangle. This command is only available when a cropping rectangle has been drawn on the image. See "Section 2.2: Cropping" for further information. UnCrop (Keyboard equivalent 'u') Returns the image to its normal, uncropped state. This command is only available after the image has been cropped. See "Section 2.2: Cropping" for further information. AutoCrop (Keyboard equivalent 'A') Crops off any constant borders that exist in the image. It will crop to the smallest rectangle that encloses the 'interesting' sec- tion of the image. It may not always appear to work because of minor invisible color changes in the image. As such, it works best on computer-generated images, and not as well on scanned images. 8 Rev: 2.10 Feb 26, 1992 xv(l) Section 3.5: The Display Modes Menu In addition to displaying an image in a window, _x_v can also display images on the root (background) window of your X display. There are a variety of ways that _x_v can display an image on the root window. The Display Modes popup menu lets you select where (and how) _x_v will display the image. Click on the Display Modes button in the _x_v _c_o_n_t_r_o_l_s window, and hold the mouse button down. This will cause the Display Modes menu to pop up. The current display mode will be shown with a check mark next to it. To select a new mode, drag the mouse down to the desired mode, and release the mouse button. It is not possible for _x_v to receive button presses or keyboard presses in the root window. As such, there are several functions that cannot be used while in a 'root' mode, such as pixel tracking and image cropping. If you want to do such things, you'll have to temporarily return to 'window' mode, and return to 'root' mode when you're finished. Also, when you are in a 'root' mode, you will not be able to get rid of the _x_v _c_o_n_t_r_o_l_s window. At best you can iconify it (using your window manager). (The reason for this is that if you ever got rid of it there'd be no way to get it back.) Window Displays the image in a window. If you were previously in a 'root' mode, the root window will also be cleared. Root: Tiled The image is displayed in the root window. One image is displayed aligned with the top-left corner of the screen. The image is then duplicated towards the bottom and right edges of the screen, as many times as necessary to fill the screen. Root: Integer Tiled Similar to Root: Tiled, except that the image is first shrunk so that its width and height are integer divisors of the screen's width and height. This keeps the images along the bottom and right edges of the screen from being Normal, Dbl Size, etc.) will lose the 'integer'-ness of the image. Root: Mirrored Tiles the original image with versions that have been horizontally flipped, vertically flipped, and both horizontally and vertically flipped. This gets rid of the sharp dividing lines where tiled images meet. The effect is quite interesting. Rev: 2.10 9 xv(l) Feb 26, 1992 Root: Integer Mirrored Like Root: Mirrored, but also does the integer-ization described under the Root: Integer Tiled entry. Root: Center Tiled Like Root: Tiled, but it positions the images so that one of them is centered on the screen, and the rest are tiled off in all direc- tions. Visually pleasing without the image size distortion associ- ated with Root: Integer Tiled. Root: Centered Displays a single image centered in the root window, surrounded by black. Root: Centered, Warp Displays a single image centered in the root window, surrounded by a black and white 'warp' pattern, which produces some mildly visu- ally pleasing Moire effects. Root: Centered, Brick Displays a single image centered in the root window, surrounded by a black and white 'brick' pattern. Note: The three 'centered' modes (Root: Centered, Root: Centered, Warp, and Root: Centered, Brick, but not Root: Center Tiled) require the crea- tion of a Pixmap the size of the screen. This can be a fairly large request for resources, and will fail on a color X terminal with insuffi- cient memory. They can also require the transmission of considerably more data than the other 'root' modes. If you're on a brain-damaged X terminal hanging off a slow network, you should probably go somewhere else. Barring that, you should certainly avoid the 'centered' modes. Also note: If you quit _x_v while displaying an image on the root window, the image will remain in the root window, and the colors used by the image will remain allocated. This is generally regarded as correct behavior. If you decide you want to get rid of the root image to free up resources, or simply because you're sick of seeing it, the quickest route is to use run 'xv -clear', which will clear the root window, release any allocated colors, and exit. Alternately, _x_s_e_t_r_o_o_t and any other X program that puts things in the root window should be able to do the trick as well. Section 3.6: The 24-bit Conversion Menu _x_v can currently only operate on 8-bit images. Whenever you load a 24- bit image (such as JPEG, TIFF, PPM, etc) it is immediately converted into an 8-bit colormapped image using one of three algorithms. 10 Rev: 2.10 Feb 26, 1992 xv(l) Fast Converts 24-bit images into 8-bit images by dithering with a fixed 6x6x6 RGB colormap. It is the quickest of the three algorithms, but also generally produces the worst images. It can also be selected via the '-quick24' command-line option or X resource. Slow The default algorithm. Takes about twice as long as the fast algo- rithm. Uses the median-cut algorithm to pick a set of 256 colors, and then dithers using these colors. It can be selected via the '-slow24' command-line option or X resource. Best By far and away the slowest of the algorithms. It can take up to ten times as long as the 'slow' algorithm. It uses a cleverer ver- sion of the median-cut algorithm to pick a better set of colors than the slow algorithm. It does not dither. This might look best if you're going to be expanding the image by very much, as the dithering in the other two algorithms becomes very noticable. You can also select this option via the '-best24' command-line option or X resource. Section 3.7: Working With Multiple Files _x_v provides a a set of controls that let you conveniently operate on a list of images. To use the following commands, you'll have to start up _x_v with a list of filenames. For example, you could type 'xv *.gif' (assuming, of course, that you have a bunch of files that end with the suffix '.gif' in the current directory). The filenames are listed in a scrollable window. The current selection is shown in reverse video. If there are more names than will fit in the window, the scrollbar will be enabled. Section 3.7.1: Operating a List Window The scrollbar operates as follows: o+ clicking in the top or bottom arrow of the scrollbar scrolls the list by one line in the appropriate direction. It will continue to scroll the list as long as you hold the mouse down. o+ The thumb (the small white rectangle in the middle of the scrollbar) shows roughly where in the list you are. You can change your posi- tion in the list by clicking and dragging the thumb to another posi- tion in the scrollbar. The list will scroll around as you move the thumb. o+ You can scroll the list up or down a page at a time by clicking in the grey region between the thumb and the top or bottom arrows. Rev: 2.10 11 xv(l) Feb 26, 1992 If you click on a name in the list, that name will become highlighted. You can drag the highlight bar up and down, and the list will scroll appropriately. It is also possible to control the list window from the keyboard. In all cases, you must make sure that the window sees the keypress. Gen- erally, this means you have to have the cursor inside the window, though your window manager may also require you to click inside the window first. o+ The up and down arrow keys move the highlight bar up and down. If the bar is at the top or bottom of the window, the list will scroll one line. o+ The page up and page down keys scroll the list up or down a page at a time. o+ Pressing the home key will jump to the beginning of the list. Press- ing the end key will jump to the bottom of the list. Section 3.7.2: The File Commands You can directly view any image in the list by double-clicking on its filename. If _x_v is unable to load the file (for any of a variety of reasons), it'll display an error message and put up the default image, the _x_v logo. Next (Keyboard equivalent <space>) Attempts to load the next file in the list. If it is unable to load the next file, it will continue down the list until it suc- cessfully loads a file. If it gets to the bottom of the list without successfully loading a file, it will put up the default image. Previous (Keyboard equivalent <backspace>) Attempts to load the previous file in the list. If it is unable to load the previous file, it will continue up the list until it suc- cessfully loads a file. If it gets to the top of the list without successfully loading a file, it will put up the default image. Delete (Keyboard equivalent <ctrl-D>) This command lets delete the currently selected file from the list (and optionally delete the associated disk file). Note that the currently selected file is the one with the highlight bar on it. While this is generally the same as the currently displayed image, it doesn't have to be. The Delete command will pop-up a window asking you what you want to delete. Your choices are: 12 Rev: 2.10 Feb 26, 1992 xv(l) o+ List Entry, which will remove the highlighted name from the list. (Keyboard equivalent: the enter key) o+ Disk File, which will remove the highlighted name from the list and also delete the associated disk file. This removes unwanted images, just like manually typing 'rm <filename>' in another window. (Keyboard equivalent: <ctrl-D>) o+ Cancel, which lets you get out of the Delete command without actually deleting anything. (Keyboard equivalent: the esc key) Section 3.7.3: Image Reloading It is occasionally desirable to reload an image file because the con- tents of the file have changed. For example, you could be downloading a file, and you might want to keep reloading the file to check on the pro- gress of the download. Or perhaps you have a program that generates images, and you'd like to view these images without any manual interven- tion. _X_V provides a way to reload an image via an external signal. If you send the xv process a SIGQUIT signal ('kill -QUIT _p_i_d', or currently selected file. (The one that is currently highlighted in the _x_v _c_o_n_- _t_r_o_l_s window filename list.) This behavior is exactly the same as hit- ting '<return>' in the _x_v _c_o_n_t_r_o_l_s window. If _x_v is currently in a state where hitting '<return>' in the controls window won't load an image (ie, some pop-up dialog box is grabbing all such events), then sending this signal wonUt work either. An idea: You could write a 'clock' program that, once a minute, gen- erates a really spiffy looking picture of the current time (with color gradations, 3d extruded numbers, whatever), then sends _x_v the signal to reload the generated image. Section 3.8: The Grab Command The Grab command works as follows: click on the Grab button in the _x_v _c_o_n_t_r_o_l_s window, or type a <ctrl-G> key in any active _x_v window (except for the JPEG, PostScript, and TIFF 'save' dialog boxes). The terminal will beep once, and the cursor will change to a cross. The screen will remain frozen until you complete the Grab command. You can Grab an arbitrary region of the screen by clicking the _L_e_f_t mouse button and dragging a rectangle in exactly the same way you draw a cropping rectangle. When you let go of the mouse button, the contents of this rectangle will be read from the screen and loaded into _x_v. Alternately, you can grab the entire contents of a window (including its frame) by clicking the _M_i_d_d_l_e mouse button anywhere inside the chosen window. If you click the _M_i_d_d_l_e mouse button somewhere on the root win- dow, the entire screen will be loaded into _x_v. Rev: 2.10 13 xv(l) Feb 26, 1992 Or, alternately, you can simply abort the Grab command by clicking the _R_i_g_h_t mouse button anywhere on the screen. You can use the Grab command for a wide variety of purposes. For exam- ple, you can use it to print the contents of any window (or the whole screen) by grabbing the appropriate image and then saving it as a PostScript file. You can use the Grab command, in conjunction with the Zoom and UnZoom commands, as an effective replacement for the _x_m_a_g program. You can also use the Grab command to pick 'just the right colors' for any application. Simply start the application in question, Grab the window into _x_v, and use the colormap editor to twiddle the colors around to your heart's content. Note: The Grab command does not work on Macintoshes running _M_a_c_X in a rootless mode, which isn't too surprising, if you think about it... Section 3.9: Other Commands Info (Keyboard equivalent 'i') Opens and closes the _x_v _i_n_f_o window. See "Section 4: The Info Win- dow" for more details. ColEdit (Keyboard equivalent 'e') Opens and closes the _x_v _c_o_l_o_r _e_d_i_t_o_r window. See "Section 5: The Color Editor" for more details. Load (Keyboard equivalent <ctrl-L>) Opens the _x_v _l_o_a_d window. See "Section 6: The Load Window" for more details. Save (Keyboard equivalent <ctrl-S>) Opens the _x_v _s_a_v_e window. See "Section 7: The Save Window" for more details. Quit (Keyboard equivalent 'q') Quits out of the program. SECTION 4: THE INFO WINDOW Section 4.1: Overview _x_v provides a window to display information about the current image, 14 Rev: 2.10 Feb 26, 1992 xv(l) color allocation, expansion, cropping, and any error messages. This window can be opened by issuing the Info command. (Click on the Info button in the _x_v _c_o_n_t_r_o_l_s window, or type 'i' in any open _x_v window.) You can close the window by using the Info command while the window is open. You can also close the window by clicking anywhere inside it. The top portion of the window displays the program name, revision date, and patchlevel. It also shows the University of Pennsylvania shield, the GRASP Lab logo, the copyright notice, and of course, the author's name. Section 4.2: The Fields The "Filename" field displays the name of the currently loaded file. The name is displayed without any leading pathname. If there is no currently loaded image (you're looking at the default image) this field will display "<none>". The "Format" field displays information describing what image format the file is stored in, and how large the file is (in bytes). The "Resolution" field shows the width and height (in image pixels) of the loaded image. Note that this does not necessarily have anything to do with the size of the image currently displayed on your screen. These numbers do not change as you modify the display image. The "Cropping" field displays the current state of any cropping activity. If you are looking at the entire (uncropped) image, and there is no cropping rectangle drawn, this field will show "<none>". If you draw a cropping rectangle, or if you are viewing cropped portion of image, this field will display something like "247x128 rectangle start- ing at 132,421". See "Section 2.2: Cropping" for more details. The "Expansion" field gives you information about how the image is displayed. It will display something like "1.58 x 1.37 (505 x 273)". This tells you that the current displayed image is 505 pixels wide and 273 pixels high, and that it is 1.58 times wider and 1.37 times higher than the internal image (which, in this case, had a size of 320x200). The "Colors" field gives you detailed information on how well (or poorly) color allocation went. If everything went reasonably well it will display something like: Got all 67 desired colors. (66 unique) This means that 67 entries in the image's colormap were used in the image, but that only 66 of these colors were different, as far as the X server was concerned. See "Appendix E: Color Allocation" for a complete discussion of how colors are allocated, and what the "Colors" field can tell you. Rev: 2.10 15 xv(l) Feb 26, 1992 Note that the fields are filled in as information becomes available. As such, they can be used as a rough 'progress indicator' when loading images. When you begin loading, all the fields are cleared. Once the image has been successfully loaded, the top three fields (Filename, For- mat, Resolution) are filled in. Once the colors have been allocated, and the display image generated, the bottom three fields are shown (Cropping, Expansion, and Colors). Section 4.3: Status Lines The bottom two lines in the info window display various error messages, warnings, and status information. These two lines are also duplicated in the _x_v _c_o_n_t_r_o_l_s window. The upper line is the more commonly used. It normally displays a one- line summary of the current image and color allocation success. If an error occurs, it will be displayed on this line as well. The lower line is used to display warning messages. SECTION 5: THE COLOR EDITOR Section 5.1: Overview The _x_v _c_o_l_o_r _e_d_i_t_o_r provides a powerful system for manipulating color images. Since there are many different reasons why a person would want to modify an image's colors, and many different types of images that may need modification, there is no one color manipulation tool that would be 'best' for all purposes. Because of this problem, _x_v gives the user three different color tools, all of which can be used simultaneously. o+ Colormap Editing: This tool lets you arbitrarily modify individual colormap entries. Useful for modifying the color of captions or other things that have been added to images. Also works well on images that have a small number of colors, such as images generated by 'drawing' or CAD programs. It's also an easy way to spiff up bor- ing 1-bit black and white images. o+ HSV Modification: This tool lets you alter the image globally in the HSV colorspace. (See "Appendix D: RGB and HSV Colorspaces" for more info.) Here are examples of the sort of things you can do with this tool: o+ turn all the blues in an image into reds o+ change the tint of an image o+ change a greyscale image into a mauve-scale image 16 Rev: 2.10 Feb 26, 1992 xv(l) o+ increase or decrease the amount of color saturation in an image o+ change the overall brightness of an image o+ change the overall contrast of an image o+ RGB Modification: This tool lets you route the red, green, and blue color components of an image through independent mapping functions. The functions can either be the standard gamma function, or any arbi- trary function that can be drawn with straight line segments or a cubic spline. See "Section 5.3.4: The Intensity Graph" for more info about graph functions. The major use of the RGB Modification tool is to correct for the differ- ing color response curves of various color monitors, printers, and scanners. This is the tool to use when "the image is too red", for instance. These three tools are tied together in a fixed order. The Colormap Editing tool operates on the original colors in the image. The output of this tool is piped into the HSV Modification tool. Its output is piped into the RGB Modification tool. The output from the RGB Modifica- tion tool is what actually gets displayed. In addition there is a collection of buttons that control the _x_v _c_o_l_o_r _e_d_i_t_o_r as a whole (more or less). Don't Panic! It's not as complicated as it looks. Section 5.2: The Colormap Editing Tool The top portion of this window shows the colormap of the current image. There are 16 cells across, and up to 16 rows down, for a maximum of 256 color cells. Only cells actually used somewhere in the image are shown in this array. The currently selected color cell is shown with a thick border. You can change the selection by clicking anywhere in the array. If you drag the mouse through this area, you'll see the dials at the bottom change to track the current pixel values. You can also select a color cell by clicking anywhere in the image win- dow. Whichever pixel value you were on when you let go of the mouse will become the new selected color cell. You can define a smoothly gradated range of colors by _L_e_f_t clicking on the color cell that marks the 'start' of the range, and _M_i_d_d_l_e clicking on the color cell that marks the 'end' of the range. Intervening color cells will be interpolated between the colors of the As an example: Rev: 2.10 17 xv(l) Feb 26, 1992 o+ View the 'default' image by running _x_v without specifying any filenames. o+ Open the _x_v _c_o_l_o_r _e_d_i_t_o_r window, and _L_e_f_t click on the first color cell. o+ Turn this color cell _r_e_d by setting the RGB dials to 255,0,0. o+ _L_e_f_t click on the 64th color cell (the rightmost color cell in the last complete row). o+ Turn this color cell _y_e_l_l_o_w by setting the RGB dials to 255,255,0. o+ _M_i_d_d_l_e click on the first color cell. A smooth series of _y_e_l_l_o_w_i_s_h- _r_e_d_s will be generated from the 64th color cell to the first color cell. Note that the 'direction' doesn't matter. Since certain images will have many colors that are the same, or nearly the same, it is sometimes convenient to group color cells together. Grouped color cells all take on the same color, and changing any one of them affects all of the other colors in the group. To group color cells together, do the following: o+ Hold down the <shift> key. o+ Left click on one color cell that you would like to be in the group o+ Right click on other color cells that you wish to be in this group. (Right clicking on cells that are already selected will de-select them.) o+ Release the <shift> key when you're done. You can create as many groups as you like. You can use this grouping/ungrouping technique to copy colors from one color cell to another. Left click on the source color cell, Right click on the destination color cell, and Right click on the destination color cell again (to ungroup it). Section 5.2.1: Using the Dial Controls At the bottom the Colormap Editing tool are three dials that let you set the color of the current color cell (or group of cells). By default, the dials control the Red, Green, and Blue components of the RGB colorspace, but they can also control the Hue, Saturation, and Value components of the HSV colorspace. (The RGB/HSV button controls this.) Regardless of what they control, all dials in _x_v work the same way. Clicking on the single arrows increase/decrease the value by 1. Click- ing on the double arrows increase/decrease the value by a larger amount 18 Rev: 2.10 Feb 26, 1992 xv(l) (16 in this case). If you click on one of the arrows, and hold the mouse button down, the increase/decrease will repeat until you release the mouse button. You can also click in the general area of the pointer and simply drag it to the position you want. The further your mouse cursor is from the center of the dial, the more precise the control will be. While drag- ging, you do not have to keep the cursor inside the dial window. Section 5.2.2: Colormap Editing Commands ColUndo Undoes the last change made to the colormap that resulted in a color cell changing value. This includes grouping and ungrouping color cells, and changing any of the dials. Revert Undoes all color changes. Returns the colormap to its original state. Destroys any groups that you may have created. RGB/HSV Toggles the Colormap Editing dials between editing colors in terms of Red, Green, and Blue, and editing colors in terms of Hue, Saturation, and Value. Grey Turns color images into greyscale images by changing the colormap. This replaces each color cell with a greyscale representation of itself. Use the Revert command to restore the colors. RevVid This command behaves differently, depending on the setting of the RGB/HSV mode. (You can tell which mode you're in by the titles on the dials.) In RGB mode, each color component is separately 'inverted'. For example, Yellow (which is composed of full red, full green, and no blue) would turn to Blue (no red, no green, full blue). In HSV mode, only the Value (intensity) component is 'inverted'. The Hue and Saturation components remain the same. In this mode, bright colors turn to dark versions of the same color. For exam- ple, a Yellow would turn Brown. Random Generates a random colormap. This is of questionable usefulness, but it will occasionally come up with pleasing color combinations Rev: 2.10 19 xv(l) Feb 26, 1992 that you never would've come up with yourself. So it stays in. It works best on images with a small number of colors. Note that it respects cell groupings, so if your image has a lot of colors, you can create a few large groups and then use the Random command. Note: It is HIGHLY RECOMMENDED that if you're using the Colormap Editing tool, you do NOT use the HSV Modification tool or the RGB Modification tool as well. If you do, the results can be quite confusing. For exam- ple, you might edit a color cell, and set its color values to produce a purple. However, because of HSV/RGB Modification further down the line, the actual color displayed on the image (and in the color cell) is yel- low. Very confusing, indeed. Section 5.3: The HSV Modification Tool There are four separate controls in the HSV Modification tool. At the top of the window are a pair of circular controls that handle hue remap- ping. Lower down is a circular control that maps 'white' (and greys) to a specified color. There is a dial control that lets you saturate/desaturate the colors of the current information. Finally, at the bottom there is a graph window that lets you modify intensity values via an arbitrary remapping function. Section 5.3.1: Hue Remapping Controls These two dials are used to define a source and a destination range of hue values. Every hue in the source range (defined in the From dial) gets mapped to the value of the corresponding point in the destination range (defined in the To dial). Each dial has a pair of radial lines with handles at their ends. Between the two lines an arc is drawn with an arrow at one end. The wedge drawn by these lines and the arc defines a range of values (in degrees). The direction of the arc (clockwise, or counter-clockwise) determines the direction of this range of values (increasing or decreas- ing). Distributed around the dial are tick marks and the letters 'R', 'Y', 'G', 'C', 'B', and 'M'. These letters stand for the colors Red, Yellow, Green, Cyan, Blue, and Magenta, and they show where these colors appear on the circle. The range is shown numerically below the control. By default the range is '330, 30 CW'. This means that a range of values [330, 331, 332, ... 359, 0, 1, ... 28, 29, 30] has been defined. Note that (being a circle) it wraps back to 0 after 359. The range can be changed in many different ways. You can click on the 'handles' at the end of the radial lines and move them around. If you 20 Rev: 2.10 Feb 26, 1992 xv(l) click inside the dial, but not on one of the handles, you'll be able to drag the range around as a single object. There are also 5 buttons below the dial that let you rotate the range, flip the direction of the range, and increase/decrease the size of the range while keeping it cen- tered around the same value. In its default state, the To dial is set to the same range as the From dial. When the two dials are set to the same range, they are effec- tively 'turned off', and ignored. An example of hue remapping: o+ As a simple example of the sort of things you can do with the hue remapping control, we'll change the background color of the default (_x_v logo) image without changing any other colors in the image. Since the background is composed of a gradient of 64 colors, you would not want to do this with the Colormap Editing tool. It would take forever. o+ First, get the default image up on the screen by running 'xv' without giving any filenames. Open up the _x_v _c_o_l_o_r _e_d_i_t_o_r window via the ColEdit command. o+ Next, click the mouse in the image window and drag it around. You'll see that all the background pixels have the same Hue component value (240). o+ To remap this hue, simply adjust the From dial so that its range includes this Hue value. The background should change from 'blue' to a reddish color, assuming the To dial is still set to its default range (centered around 'R'). If more than the background changed color, you can shrink the From range so that it covers fewer colors. In fact, it's possible to shrink the range to the point where it only covers only a single value. Note that the values printed when you are tracking pixel values in the image are the values before the HSV Modification tool is applied. For example, the background of the default image will still claim to be blue, regardless of what color you may have changed it to. This is so that you know what Hue value you will need to remap if you want to change its color again. If you press the Reset button that is located near the hue remapping controls, it will effectively disable the hue remapping by setting the To range equal to the From range. Below the hue remapping controls are a group of 'radio buttons'. You can have up to six different hue remappings happening simultaneously. Higher numbered mappings take precedence over lower number mappings. An example of multiple hue remappings: o+ Draw a From range that is a complete circle. The easiest way to do this is to draw a range that is nearly a full circle, then click and Rev: 2.10 21 xv(l) Feb 26, 1992 hold down the 'increase range' button located below the From range dial until the range stops getting bigger. o+ Copy this range to the To range by pressing the Reset button. o+ Rotate the To range slightly, by either clicking and dragging any- where in the To range dial, or by using the 'rotate clockwise' and 'rotate counter-clockwise' buttons located below the To range. o+ You've just built yourself what is effectively a tint control. o+ Now, suppose, you'd like to adjust the background color of your (tint-modified) image, without affecting anything else. Clicking on the background in the image window reveals that the background still has an (original) hue of 240. To modify this hue without affecting anything else, we'll need a second hue remapping. o+ Click on the 2 radio button. The dials will change to some other default setting. As before, set the From range to encompass the value 240, preferably as 'tightly' as possible, and set the To range to produce the desired background color. Note that the six hue remappings are not 'cascaded'. The output of one remapping is not fed as input into any of the other hue remappings. The hue remappings always operate on the hue values in the original image. In this example, if remapping #1 adds 32 to all hue values, thereby map- ping the blue background (value 240) into a purple-blue (value 272), remapping #2 still sees the background at 240, and can remap it to any- thing it likes. Similarly, in the same example, if remapping #1 has mapped a green-blue color (value 208) into blue (value 240), remapping #2 will not map this into another color. As far as remapping #2 is con- cerned, that green-blue is still green-blue. If it seems complicated, I'm sorry. It is. Section 5.3.2: The White Remapping Control In the HSV colorspace, 'white' (including black, and all the greys in between) has no Hue or Saturation components. As such, it is not possi- ble to use the hue remapping controls to change the color of white pix- els in the image, since they have no 'color' to change. The white remapping control provides a way to add Hue and Saturation components to all the whites in the image. It consists of a movable point in a color dial. The angle of the dot from the center of the dial determines the Hue component. The distance of the dot from the center of the dial determines the Saturation component. The further the dot is from the center of the dial, the more saturated the color will be. You can control the white remapping control in several ways. You can click on the handle and drag it around with the mouse. There are also four buttons provided under the dial. One pair allows you to rotate the 22 Rev: 2.10 Feb 26, 1992 xv(l) handle clockwise and counter-clockwise without changing its distance from the center. The other pair of buttons lets you change the distance between the handle and the center without changing the angle. The current Hue and Saturation values provided by the control is displayed below the dial. The first number is the Hue component, in degrees, and the second is the Saturation component, as a percentage. There is also a checkbox that will let you turn off the white remapping control. This lets you quickly compare your modified 'white' with the original white. You can also effectively disable the white remapping control by putting the handle back in the center of the control. The easiest way to do this is to click and hold the 'move towards center' button until the saturation gets down to 0%. Example: o+ Press the Grey control in the Colormap Editing tool. This turns all the colors in the image into shades of grey. o+ Drag the handle in the white remapping control halfway down towards the 'R' mark. The Hue and Saturation values should be roughly 0- degrees and 50%. The image should now be displayed in shades of pink. Section 5.3.3: The Saturation Control The saturation control lets you globally increase or decrease the color saturation of the image. In effect, it is much like the 'color' control on most color televisions. The saturation control is a dial that operates exactly like the dials described in "Section 5.2.1 Using the Dial Controls". In short, you can click and hold down any of the four buttons in the bottom of the control to increase or decrease the control's value. You can also click on the dial itself and move the pointer around directly. The saturation control has values that range from '-100%' to '+100%'. At its default setting of '0%', the saturation control has no effect on the image. As the values increase, the colors become more saturated, up to '+100%' where every color is fully saturated. Likewise, as values decrease, the colors become desaturated. At '-100%', every color will become a completely desaturated (i.e., a shade of grey). Note that this control is applied after the the White Remapping control, so if you 'greyify' the image by completely desaturating it, you will not be able to color it using the White Remapping control. Unless you're trying for some special effects, the useful range of this control is probably '+/-20%'. Also note that the control will have no effect on shades of grey, as they have no color to saturate. Rev: 2.10 23 xv(l) Feb 26, 1992 Section 5.3.4: The Intensity Graph The intensity graph allows you to change the brightness of the image, change the contrast of the image, and get some unique effects. The intensity graph is a function that lets you remap intensity values (the Value component in HSV Colorspace) into other intensity values. The input and output values of this function both range from 0 to 255. The input values range along the x axis of this graph (the horizontal). For every input value (point along the x axis) there is a unique output value determined by the height of the graph at that point. In the graph's default state, the function is a straight line from bottom-left to top-right. In this case, each input value produces an equivalent output value, and the graph has no effect. There are a number of 'handles' along the graph. These provide your major means of interacting with the graph. You can move them around arbitrarily, subject to these two constraints: the handles at the far left and far right of the graph can only be moved vertically, and han- dles must remain between their neighboring handles for the graph to remain a proper function. The handles are normally connected by a spline curve. To see this, move one of the handles by clicking and dragging it. (Note that the _x,_y position of the current handle is displayed while the mouse button is held down.) The function will remain a smoothly curved line that passes through all the handles. You can change this behavior by putting the function into 'lines' mode. Press the 'lines' button (the second button down from the top). The function will change to a series of line seg- ments that connect the handles. Press the 'spline' button (the top but- ton) to go back to 'spline' mode. The next two buttons let you add or delete handles. The 'add handle' button will insert a handle into the largest 'gap' in the function. The 'delete handle' button will remove a handle from the smallest 'gap' in the function. You can have as little as 2 handles, or as many as 16. Note that as the number of handles gets large, the spline will start getting out of control. You may wish to switch to 'lines' mode in this case. The 'Reset' button puts everything back on a straight line connecting bottom-left to top-right (a 1:1 function). It does not change the number of handles, nor does it change the x-positions of the handles. The 'Gam' button lets you set the function curve by entering a single number. The function is set equal to the gamma function: Y = 255 * (I/255) ^ (1/g) where I is the input value (0-255), g is the gamma value, and Y is the computed result. Gamma values (for our purposes) can range between 0 and 10000, non- 24 Rev: 2.10 Feb 26, 1992 xv(l) inclusive. o+ A gamma value of '1.00' results in the normal 1:1 straight line. o+ Gamma values of less than 1.00 but greater than 0.00 result in 'exponential' curves, which will dim the image. o+ Gamma values greater than 1.00 result in 'logarithmic' curves, which will brighten the image. Try it and see. There is a shortcut for the 'Gam' button. Type 'g' while the mouse is inside the graph window. Also, touching any of the handles after a 'Gam' command will put the graph back into its 'normal' mode. (Either 'spline' or 'lines' depend- ing on which of the top two buttons is turned on.) Generally, whenever you move a graph handle and let go of it, the image will be redrawn to show you the effects of what you've done. This can be time-consuming if you intend to move many points around. You can temporarily prevent the redisplay of the image by holding down a <shift> key. Continue to hold the <shift> key down while you move the handles to the new position. Release the <shift> key when you're done, and the image will be redisplayed. Section 5.4: The RGB Modification Tool The RGB Modification tool is a collection of three graph windows, each of which operate on one of the components of the RGB colorspace. This tool lets you perform global color-correction on the image by boosting or cutting the values of one or more of the RGB color components. You can use this to correct for color screens that are 'too blue', or for color printers that produce 'brownish' output, or whatever. The graphs work exactly as explained in "Section 5.3.4: The Intensity Graph". Neat Trick: In addition to color-correction, you can use the RGB modifi- cation tool to add color to images that didn't have color to begin with. For instance, you can 'pseudo-color' a greyscale image. An example of pseudo-coloring: o+ Adjust the Red graph so that there is a strong red presence on the right side of the graph, and none on the left, or in the middle. o+ Adjust the Green graph so that there is a strong green presence in the middle of the graph, and none on the left or right. o+ Adjust the Blue graph so that there is a strong blue presence on the left side of the graph, and none on the left, or in the middle. Rev: 2.10 25 xv(l) Feb 26, 1992 You now have a transformation that will take greyscale images and display them in pseudo-color, using a 'temperature' color scheme. Neato! Section 5.5: The Color Editor Controls These buttons provide general control over the whole _x_v _c_o_l_o_r _e_d_i_t_o_r window. You can display the image with or without color modification, save and recall presets, and undo/redo changes. Also, convenience con- trols are given for performing some of the most common operations on the Intensity graph. Apply (Keyboard equivalent 'p') Displays the image using the current HSV and RGB Modifications. Also turns the 'Display with HSV/RGB mods' checkbox on. (See below.) This is only useful when the 'Auto-apply HSV/RGB mods' checkbox is off. NoMod Displays the image without any HSV or RGB Modifications. Also turns the 'Display with HSV/RGB mods' checkbox off. Reset (Keyboard equivalent 'R') Resets all HSV and RGB controls to their default settings. Doesn't affect the Colormap Editing tool. Undo Undoes the last change to the HSV or RGB controls. It may be helpful to think of _x_v as maintaining a series of 32 'snapshots' of the HSV and RGB controls. You are normally looking at the last frame in this series. The Undo control moves you back- wards in the series. Redo Only available after you've hit Undo. Moves you forward in the 'snapshot' series described above. Note that if you have hit Undo a few times (i.e., you're now looking at some frame in the middle of the series), and you change an HSV or RGB control, all subse- quent frames in the series are thrown away, and the current state becomes that last frame in the series. 1,2,3,4 Pressing any of these buttons recalls a preset (a complete set of values for the HSV and RGB controls). 26 Rev: 2.10 Feb 26, 1992 xv(l) Set Used in conjunction with the Reset,1,2,3,4 buttons to store the current settings of the HSV and RGB controls into a preset. To do so, press the Set button, and then press one of the Reset,1,2,3,4 buttons. The current HSV and RGB control settings will be stored in that preset, as long as _x_v continues running. The values will be lost when the program exits. It is also possible to save these values permanently. See the CutRes button (below) and "Section 9: Modifying XV Behavior" for more details. CutRes Copies the current settings of the HSV and RGB controls, as text, into the X server's cut buffer. You can then use a text editor to paste these values into your '.Xdefaults' (or '.Xresources') file. This lets you save the current settings 'permanently'. See "Sec- tion 9: Modifying XV Behavior" for more details. Close This button closes the _x_v _c_o_l_o_r _e_d_i_t_o_r window. Brite Brightens the image by moving all the handles in the Intensity graph up by a constant amount. Dim Darkens the image by moving all the handles in the Intensity graph down by a constant amount. Sharp Increases the contrast of the image by moving handles on the left side of the Intensity graph down, and handles on the right side up. Dull Decreases the contrast of the image by moving handles on the left side of the Intensity graph up, and handles on the right side down. Norm (Keyboard equivalent 'N') Normalizes the image so that the darkest pixels in the image are given an intensity of '0', and the brightest pixels in the image are given an intensity of '255'. Intermediate colors are interpo- lated accordingly. This forces the image to have the full (max- imum) dynamic range. HistEQ (Keyboard equivalent 'H') Runs a histogram equalization algorithm on the currently displayed region of the image. This is, if you're cropped, it will only run the algorithm on the cropped section. Note, however, that the only modification it makes to the image is to generate a bizarre Rev: 2.10 27 xv(l) Feb 26, 1992 corrective Intensity curve. As such, if you HistEQ a section of the image, then UnCrop, the rest of the image will probably not be what you'd want. Also note that the histogram curve will 'go away' if you touch any of the handles in the Intensity graph window, just like a 'gamma' curve would. The 'Display with HSV/RGB mods' checkbox tells you whether or you're looking at a modified image (checked) or the 'raw', unmodified image (unchecked). The Apply and NoMod buttons change the setting of this checkbox, and you can also change the checkbox directly by clicking on it. The 'Auto-apply HSV/RGB mods' checkbox controls whether or not the pro- gram regenerates and redisplays the image after each change to an HSV or RGB control. By default, this checkbox is turned on, so that you can easily see the results of your modifications. However, in the case that you want to make a large number of changes at once, it might be prefer- able to turn automatic redisplay off for a while, to speed things up. The 'Auto-reset on new image' checkbox controls whether or not the HSV and RGB controls are Reset back to their default values whenever a new image is loaded up. By default, this is also turned on, as when you're playing with the HSV/RGB controls, you probably only want to affect the current image, and not all subsequently loaded images as well. SECTION 6: THE LOAD WINDOW The _x_v _l_o_a_d window lets you load and view images interactively, without specifying them on the command line when you start _x_v. The load window shows the contents of the current directory in a scrol- ling window. The files will be sorted alphabetically, with all the directories (and symbolic links to directories, if your operating system supports them) displayed first. This list window operates in the same way that the one in the _x_v con- trols window works. (See "Section 3.7.1: Operating a List Window" for details.) In short, you can operate the scroll bar, drag the highlight bar around the window, and use the up-arrow, down-arrow, Home, End, Page Up, and Page Down keys on your keyboard. Whenever you click on a name in the list (or otherwise change the posi- tion of the highlight bar), the name of the highlighted file is copied to the "Load file" text entry region, located below the list window. Pressing the Ok button (or typing <return>) will cause the program to attempt to load the specified file. If the load attempt is successful, the load window will disappear, and the new image will be displayed. Otherwise, an error message will be displayed, and the load window will remain visible. The Browse checkbox overrides this behavior, and keeps the load window visible until it is explicitly closed via the Cancel button. This is 28 Rev: 2.10 Feb 26, 1992 xv(l) handy if you're using _x_v to 'wander around a directory tree', and plan to be using the Load command quite often. If the image is successfully loaded, its name will be added to the _x_v _c_o_n_t_r_o_l_s window list. This will let you quickly reload it later without have to go through the _x_v _l_o_a_d window again. You can also load a file by double-clicking on its name in the file list. If the specified filename begins with a '!' or '|' character, the filename will be interpeted as a shell command to run. The leading '!' or '|' gets stripped off, and the rest of the line is fed to the default system shell. The command is expected to generate an image in one of the formats that _x_v recognizes. This image is expected to be the stdout of the specified command. If the command returns non-zero, it is assumed that the command failed, and no image is loaded. You can pipe multiple commands together. For example, loading "! xwd | xwdtopnm" would run _x_w_d to generate a window dump, pipe that to _x_w_d_t_o_p_n_m to con- vert it to a PPM file, which in turn is piped to _x_v. If the specified file is a directory, _x_v will figure that out and (instead of loading it) will 'cd' to that directory, and display its contents in the list window. Above the list window is a pop-up menu button, much like the Display Modes button in the _x_v _c_o_n_t_r_o_l_s window. It normally displays the name of the current directory. If you click this button, and hold the mouse down, the complete path will be shown, one directory per line. You can go 'up' the directory tree any number of levels, all the way up to the root directory, by simply selecting a directory name in this list. For those who prefer the direct approach, you can simply type file or directory names in the "Load file" text entry region. If you type a directory name and hit <return>, _x_v will 'cd' to that directory and display its contents in the list window. If you type a file name and hit <return>, _x_v will attempt to load the file. You can enter relative paths (relative to the currently displayed directory), absolute paths, and even paths that begin with a '~'. The "Load file" text entry region supports a number of emacs-like edit- ing keys. Ctrl-F moves the cursor forward one character Ctrl-B moves the cursor backward one character Ctrl-A moves the cursor to the beginning of the line Ctrl-E moves the cursor to the end of the line Ctrl-D deletes the character to the right of the cursor Ctrl-U clears the entire line Rev: 2.10 29 xv(l) Feb 26, 1992 Ctrl-K clears from the cursor position to the end of the line. If the filename is so long that it cannot be completely displayed in the text entry region, a thick line will appear on the left or right side (or both sides) of the region to show that "there's more over this way". Pressing the Rescan button will rescan the current directory. While the contents of the current directory are read each time the load window is opened, it is perfectly possible (given a multitasking operating system) that some other program may add, delete, or rename files in the current directory. _X_V would not know if this happened. The Rescan button gives you an easy way of 'kicking' _x_v into looking again. SECTION 7: THE SAVE WINDOW The _x_v _s_a_v_e window lets you write images back to disk, presumably after you've modified them. You can write images back many different formats, not just the original format. Warning! Images are saved as they are currently shown (at the current size, with the current color modifica- tion, rotation, cropping, etc. applied). The only exception to this rule is if you are on a 1-bit B/W display. The fact that images have to be stippled in black and white in order to be displayed on such a screen doesn't count as 'modification', and the file won't be saved 'as displayed'. You can manipulate and save full-color images on such a display, even if you can't really see them. For the most part, the _x_v _s_a_v_e window operates exactly like the _x_v _l_o_a_d window. (See "Section 6: The Load Window" for details.) Only the differences are listed here. When the window is opened, it should have the filename of the currently loaded file already entered into the text entry region. If you change directories, or click on a file name in the list window, this name will be cleared and replaced with the new name. At the bottom of the window are a list of possible formats in which you can save the file. If you click on one of these formats, and your filename has a recognized suffix (i.e., '.gif', '.GIF', '.pbm', etc.), the suffix portion of your filename will be replaced with the new, appropriate suffix for the selected format. You can pipe output from _x_v to other programs by using the _x_v _s_a_v_e win- dow. If the first character of the specified filename is '!' or '|', the rest of the filename is interpreted as a command to pipe the output to, in the currently selected image format. A fine use for this feature is directly printing images to a PostScript printer by selecting 'PostScript' in the formats list, and typing something like "| lpr" as the filename. In this case, _x_v will create a temporary file, write the PostScript to that file, and cat the contents of that file to the entered command. _X_V will wait for the command to complete. If the com- mand completed successfully, the _x_v _s_a_v_e window will disappear. If the command was unsuccessful, the window will remain visible. In any event, the temporary file will be deleted. 30 Rev: 2.10 Feb 26, 1992 xv(l) There is a 'Save at normal size' checkbox. Normally, when you save an image, it will be saved at the current expansion (ie, one screen pixel will map to one image pixel in the saved file. Sometimes, however, it is desirable to save an image at its original size. This is most relevant when you're viewing images larger than your screen. By default, _x_v will automatically shrink images so that they fit on the screen. If you save these images, you'll find that you've lost a lot of data, that maybe you wanted to keep. That's what this checkbox is here for. Note: certain operations, such as Smooth and Dither only affect the displayed image. If you choose to save an image at its normal size, these effects will not be in the saved image. At the bottom right side of the window there is a list of possible 'Color' variations to save. Most file formats support different 'sub- formats' for 24-bit color, 8-bit greyscale, 1-bit B/W stippled, etc. Not all of them do. Likewise, not all 'Color' choices are available in all formats. In general, the 'Color' choices do the following: Full Color Saves the image as currently shown with all color modifications, cropping, rotation, flipping, resizing, and smoothing. The image will be saved with all of its colors, even if you weren't able to display them all on your screen. For example, you can load a color image on a 1-bit B/W display, modify it, and write it back. The saved image will still be full color, even though all you could see on your screen was some B/W-dithered nightmare. Greyscale Like Full Color, but saves the image in a greyscale format. B/W Dithered Like Full Color, but before saving the image _x_v generates a 1-bit- per-pixel, black-and-white dithered version of the image, and saves that, instead. Reduced Color Saves the image as currently shown, with all color modifications, cropping, rotation, flipping, resizing, and smoothing. The image will be saved as shown on the screen, with as many or few colors as _x_v was able to use on the display. The major purpose of this is to allow special effects (color reduction) to be saved, in conjunction with the '-ncols' command line option. You will probably never need to use this. Format notes: GIF While _x_v can read both the GIF87a and GIF89a formats, it will only Rev: 2.10 31 xv(l) Feb 26, 1992 write GIF87a. This is in keeping with the GIF89 specification, which states that if you don't need any of the features added in GIF89 (which _x_v doesn't), you should continue to write GIF87, for greater compatibility with old GIF87-only readers. Since GIF only supports one format (up to 8 bits per pixel, with a colormap), there will be no size difference between a Full Color and a Greyscale image. A B/W Dithered image, on the other hand, will be considerably smaller. PM Full Color images are saved in the 3-plane, 1-band, PM_C format. Greyscale and B/W Dithered images are both saved in the 1-plane, 1-band, PM_C format. As such, there is no size advantage to saving in the B/W Dithered format. PBM (raw) Full Color images are saved in PPM format. Greyscale images are saved in PGM format. B/W Dithered images are saved in PBM format. Each of these formats are tailored to the data that they save, so PPM images are larger than PGM images, which are in turn larger than PBM images. In the raw variation of the PBM formats, the header information is written in plain ASCII text, and the image data is written as binary data. This is the more popular of the two dialects of PBM. PBM (ascii) Like PBM (raw), only the image data is written as ASCII text. As such, images written in this format will be several times larger than images written in PBM (raw). This is a pretty good format for interchange between systems because it is easy to parse. Also, since they are pure, printable ASCII text, images saved in this format can be mailed, without going through a _u_u_e_n_c_o_d_e-like pro- gram. Note that _x_v-produced PBM files may break some PBM readers that do not correctly parse comments. If your PBM reader cannot parse com- ments, you can easily edit the PBM file and remove the comment lines. A comment is everything from a "#" character to the end of the line. X11 Bitmap Saves files in the format used by the _b_i_t_m_a_p program, which is part of the standard X11 distribution. Since bitmap files are inherently 1-bit per pixel, you can only select the B/W Dithered option for this format. Sun Rasterfile Full/Reduced Color images are stored in a 24-bit RGB format, 32 Rev: 2.10 Feb 26, 1992 xv(l) Greyscale images are stored in an 8-bit greyscale format, and B/W Dithered images are stored in a 1-bit B/W format. PostScript Full/Reduced Color images are stored in a 24-bit RGB format, Greys- cale images are stored in an 8-bit greyscale format, and B/W Dith- ered images are stored in a 1-bit B/W format. _X_V writes Encapsulated PostScript, so you can incorporate _x_v- generated PostScript into many desktop-publishing programs. _X_V also prepends some color-to-greyscale code, so even if your printer doesn't support color, you can still print 'color' PostScript images. These images will be three times larger (in file size) than their greyscale counterparts, so it's a good idea to save Greyscale PostScript, unless you know you may be printing the file on a color printer at some point. Also, you should probably never need to generate B/W Dithered PostScript, as every PostScript printer I've ever heard of can print greyscale images. The only valid cases I can think of are: A) doing it for a special effect, and B) doing it to generate a much smaller (roughly 1/8th the size) PostScript file. Note: When you try to save a PostScript file, the _x_v _p_o_s_t_s_c_r_i_p_t window will pop up to let you specify how you want the image printed. (See "Section 8: The PostScript Window", for details.) JPEG _X_V writes files in the JFIF format created by the Independent JPEG Group. Full/Reduced Color images are written in a 24-bit RGB for- mat, and Greyscale images are written in an 8-bit greyscale format. B/W Dithered images should not be used, as they will probably wind up being larger than Greyscale versions of the same images, due to the way JPEG works. Note: You cannot write Reduced Color JPEG files. If you attempt to, a Full Color JPEG file will be saved. When you save in the JPEG format, a dialog box will pop up and ask you for a quality setting. '75%' is the default value, and really, it's a fine value. You shouldn't have to change it unless you're specifically trying to trade off quality for compression, or vice versa. The useful range of values is 5%-95%. TIFF Full/Reduced Color images are written in a 24-bit RGB format, Greyscale images are written in an 8-bit greyscale format, and B/W Dithered images are written in a 1-bit B/W format. When you save in the TIFF format, a dialog box will pop up and ask you which type of image compression it should use. None, LZW, and PackBits compression types are available for Full/Reduced Color, Greyscale, and B/W Dithered modes. In addition, there are two B/W Dithered-only algorithms, CCITT Group3 and CCITT Group4. Rev: 2.10 33 xv(l) Feb 26, 1992 SECTION 8: THE POSTSCRIPT WINDOW The _x_v _p_o_s_t_s_c_r_i_p_t window lets you describe how your image should look when printed. You can set the paper size and the image size, position the image on the paper, and print in 'portrait' or 'landscape' mode. The majority of the _x_v _p_o_s_t_s_c_r_i_p_t window is taken up by a window that shows a white rectangle (the page) with a black rectangle (the image) positioned on it. You can position the image rectangle anywhere on the page. The only constraint is that the center of the image (where the two diagonal lines meet) must remain on the page. Only the portion of the image that is on the page will actually be printed. The image can be (roughly) positioned on the page by clicking in the image rectangle and dragging it around. As you move the image, the "Top" and "Left" position displays will show the size of the top and left margins (the distance between the top-left corner of the page and the top-left corner of the image). You'll note that you have limited placement resolution with the mouse. If you want to fine-position the image, you can use the arrow keys to move the image around. The arrow keys will move the image in .001" increments. You can hold them down, and they will auto-repeat. You can also hold a <shift> key down while using the arrow keys. This will move the image in .01" increments. You can change the size of the printed image by adjusting the "Width" or "Height" dials. Normally, the dials are locked together, to keep the aspect ratio of the image constant. You can unlock the dials by turning the off the checkbox located below the dials. As you change the dials, the size of the image (when printed) is displayed below, in inches and in millimeters. The current resolution of the image is also displayed below. The "Resolution" numbers tell you how many image pixels will be printed per inch. Located below the 'page' rectangle are a set of radio buttons that let you specify the current paper size (8.5" x 11", 8.5" x 14", 11" x 17", A4, B5, 4"x5", and 35mm), and orientation (Portrait and Landscape). The Center button will center the image on the page. The Maxpect button will make the image as large as possible (maintaining half-inch margins on all sides) without changing the aspect ratio. There are a pair of small buttons located next to the "Left" and "Top" displays. Clicking the "Left" one will cycle between displaying the "Left" margin, the "Right" margin, and the "Center X" position (the dis- tance from the left edge of the paper to the center of the image). Clicking the "Top" display's button will cycle between displaying the size of the "Top" margin, the size of the "Bottom" margin, and the "Center Y" position (the distance from the top edge of the paper to the center of the image). 34 Rev: 2.10 Feb 26, 1992 xv(l) At the top of the _x_v _p_o_s_t_s_c_r_i_p_t window are a pair of checkboxes. The "preview" checkbox lets you specify whether or not to include a b/w pre- view of the image in the PostScript file. Certain desktop publishing programs may make use of such a preview. The 'compress' checkbox lets you specify whether or not to generate compressed 8-bit PostScript. This is particularly handy if you're gen- erating color PostScript as color PostScript files are normally three times larger than their greyscale counterparts. Compression can shrink these color PostsScript files by a factor of 4:1. It has a lesser effect on greyscale images. It should be noted, however, that compressed PostScript files may take 2-3 times longer to print than uncompressed PostScript files. However, if you are connected to your laser printer via a slow 9600 baud serial line, the decreased transmis- sion time due to compressed data may more than make up for the increased execution time. You'll have to decide for yourself. Click the "Ok" button when you're finished with the _x_v _p_o_s_t_s_c_r_i_p_t win- dow. If everything is successful, the _x_v _p_o_s_t_s_c_r_i_p_t and the _x_v _s_a_v_e window will both close. If _x_v was unable to write the PostScript file, the _x_v _p_o_s_t_s_c_r_i_p_t window will close, but the _x_v _s_a_v_e window will remain open, to give you a chance to enter a different filename. SECTION 9: MODIFYING XV BEHAVIOR _X_V supports literally dozens of command line options and X11 resources. Fortunately, it is doubtful that you'll ever need to use more than a small few. The rest are provided mainly for that 'one special case' application of _x_v... Section 9.1: Command Line Options Overview If you start _x_v with the command 'xv -help', the current list of options will be displayed: xv [-] [-2xlimit] [-aspect _w:_h] [-bg _c_o_l_o_r] [-black _c_o_l_o_r] [-bw _w_i_d_t_h] [-cegeometry _g_e_o_m] [-cemap] [-cgeometry _g_e_o_m] [-clear] [-cmap] [-cursor _c_h_a_r#] [-DEBUG _l_e_v_e_l] [-display _d_i_s_p] [-dither] [-expand _e_x_p] [-fg _c_o_l_o_r] [-fixed] [-geometry _g_e_o_m] [-help] [-hi _c_o_l_o_r] [-hsv] [-igeometry _g_e_o_m] [-imap] [-keeparound] [-lo _c_o_l_o_r] [-max] [-maxpect] [-mono] [-ncols _n_c] [-nglobal] [-ninstall] [-nopos] [-noqcheck] [-owncmap] [-perfect] [-quit] [-rbg _c_o_l_o_r] [-rfg _c_o_l_o_r] [-rgb] [-rmode _m_o_d_e] [-_r_o_o_t] [-_r_w] [-_s_l_o_w_2_4] [-_s_m_o_o_t_h] [-_v_i_s_u_a_l _t_y_p_e] [-_w_a_i_t _s_e_c_o_n_d_s] [-_w_h_i_t_e _c_o_l_o_r] [-_w_l_o_o_p] [-_n_o_r_e_s_e_t_r_o_o_t] [-_b_r_o_w_s_e] [-_n_o_s_t_a_t] [-_b_e_s_t_2_4] [-_q_u_i_c_k_2_4] [-_c_e_c_m_a_p] [-_c_r_o_p] [-_r_v] [-_n_o_l_i_m_i_t_s] [-_l_o_a_d_c_l_e_a_r] [_f_i_l_e_n_a_m_e ...] Rev: 2.10 35 xv(l) Feb 26, 1992 Section 9.2: General Options -help Print usage instructions, listing the current available command- line options. Any unrecognized option will do this as well. -display _d_i_s_p Specifies the display that _x_v should attempt to connect to. If you don't specify a display, _x_v will use the environment variable $_D_I_S_P_L_A_Y. -fg _c_o_l_o_r (Resource name: foreground _s_t_r_i_n_g) Sets the foreground color used by the windows. -bg _c_o_l_o_r (Resource name: background _s_t_r_i_n_g) Sets the background color used by the windows. -hi _c_o_l_o_r (Resource name: highlight _s_t_r_i_n_g) Sets the highlight color used for the top-left edges of the control buttons. -lo _c_o_l_o_r (Resource name: lowlight _s_t_r_i_n_g) Sets the lowlight color used for the bottom-right edges of the con- trol buttons, and also the background of some windows. -bw _b_w_i_d_t_h (Resource name: borderWidth _i_n_t_e_g_e_r) Sets the width of the border on the windows. Your window manager may choose to ignore this, however. Section 9.3: Image Sizing Options -geometry _g_e_o_m (Resource name: geometry _s_t_r_i_n_g) Lets you specify the size and placement of the 'image' window. It's most useful when you only specify a position, and let _x_v choose the size. If you specify a size as well, _x_v will create a window of that size, unless -fixed is specified. The geom argument is in the form of a normal X geometry string (e.g. "300x240" or "+10+10" or "400x300+10+10"). -fixed (Resource name: fixed _b_o_o_l_e_a_n) Only used in conjunction with the -geometry option. If you specify a window size with the -geometry option, _x_v will normally stretch 36 Rev: 2.10 Feb 26, 1992 xv(l) the picture to exactly that size. This is not always desirable, as it may seriously distort the aspect ratio of the picture. Specify- ing the -fixed option corrects this behavior by instructing _x_v to use the specified geometry size as a maximum window size. It will, however, preserve the original aspect ratio of the picture. For example, if you give a rectangular geometry of '320x240', and you try to display a square picture with a size of '256x256', the window opened will actually be '240x240', which is the largest square that still fits in the '320x240' rectangle that was speci- fied. -expand _e_x_p (Resource name: expand _f_l_o_a_t_i_n_g-_p_o_i_n_t) Lets you specify an initial expansion or compression factor for the picture. You can specify floating-point values. Values larger than zero multiply the picture's dimensions by the given factor. (i.e., an expand factor of '3' will make a 320x200 image display as 960x600). Factors less than zero are treated as reciprocals. (i.e., an expand factor of '-4' makes the picture 1/4th its normal size.). '0' is not a valid expansion factor. -aspect _w:_h (Resource name: aspect _s_t_r_i_n_g) Lets you set an initial aspect ratio, and also sets the value used by the Aspect control. The aspect ratio of nearly every X display (and, in fact, any civilized graphics display) is 1:1. What this means is that pixels appear to be 'square'. A 100 pixel wide by 100 pixel high box will appear on the screen as a square. Unfor- tunately, this is not the case with some screens and digitizers. The -aspect option lets you stretch the picture so that the picture appears correctly on your display. Unlike the other size-related options, this one doesn't care what the size of the overall picture is. It operates on a pixel-by-pixel basis, stretching each image pixel slightly, in either width or height, depending on the ratio. Aspect ratios greater than '1:1' (e.g., '4:3') make the picture wider than normal. Aspect ratios less than '1:1' (e.g. '2:3') make the picture taller than normal. (Useful aspect ratio: A 512x480 image that was supposed to fill a standard 4x3 video screen (pro- duced by many video digitizers) should be displayed with an aspect ratio of '5:4') Section 9.4: Color Allocation Options -ncols _n_c (Resource name: ncols _i_n_t_e_g_e_r) Sets the maximum number of colors that _x_v will use. Normally, this is set to 'as many as it can get'. However, you can set this to smaller values for interesting effect. Most notably, if you set it Rev: 2.10 37 xv(l) Feb 26, 1992 to '0', it will display the picture by dithering with 'black' and 'white'. (The actual colors used can be set by the -black and -white options, below.) -nglobal (Resource name: nglobal _b_o_o_l_e_a_n) Adjusts the way the program behaves when it is unable to get all the colors it requested. Normally, it will search the display's default colormap, and 'borrow' any colors it deems appropriate. These borrowed colors are, however, not owned by _x_v, and as such, can changed without _x_v'_s permission, or knowledge. If this hap- pens, the displayed picture will change, in a less-than-desirable direction. If you specify the -nglobal option, _x_v will not use 'global' colors. It will only use colors that it successfully allocated, which makes it immune to any color changes. It should be noted that 'use global colors' is the default because color changes aren't generally a problem if you are only using _x_v to display a picture for a short time. Color changes only really become a problem if you use _x_v to display a picture that you will be keeping around for a while, while you go and do some other work (such as using _x_v to display a background). In such cases you will want to specify -nglobal. Note: using the -ncols or -root options automatically turn on -nglobal. -rw (Resource name: rwColor _b_o_o_l_e_a_n) Tells _x_v to use read/write color cells. Normally, _x_v allocates colors read-only, which allows it to share colors with other pro- grams. If you use read/write color cells, no other program can use the colors that _x_v is using, and vice-versa. The only reason you'd do such a thing is that using read/write color cells allows the Apply function in the _x_v _c_o_l_o_r _e_d_i_t_o_r window to operate much fas- ter. -perfect (Resource name: perfect _b_o_o_l_e_a_n) Makes _x_v try 'extra hard' to get all the colors it wants. In par- ticular, when -perfect is specified, _x_v will allocate and install its own colormap if (and only if) it was unable to allocate all the desired colors. This option is not allowed in conjunction with the -root option. -owncmap (Resource name: ownCmap _b_o_o_l_e_a_n) Like '-perfect', only this option forces _x_v to always allocate and install its own colormap, thereby leaving the default colormap untouched. -cecmap (Resource name: ceditColorMap _b_o_o_l_e_a_n) Specifies whether _x_v installs the image's colormap in the _x_v _c_o_l_o_r _e_d_i_t_o_r window, as well as in the image's window. By default, the program does install the colormap in the color editor window, 38 Rev: 2.10 Feb 26, 1992 xv(l) however this can occasionally make the color editor window unread- able. (This option only apples when the '-perfect' or '-owncmap' options create their own colormaps.) -ninstall (Resource name: ninstall _b_o_o_l_e_a_n) Prevents _x_v from 'installing' its own colormap, when the -perfect or -owncmap options are in effect. Instead of installing the colormap, it will merely 'ask the window manager, nicely' to take care of it. This is the correct way to install a colormap (i.e., ask the WM to do it), unfortunately, it doesn't actually seem to work in many window managers, so the default behavior is for _x_v to handle installation itself. However, this has been seen to annoy one window manager (_d_x_w_m), so this option is provided if your WM doesn't like programs installing their own colormaps. Section 9.5: 24-bit Conversion Options The following options only come into play if you are using _x_v to display 24-bit RGB data (PPM files, color PM files, JPEG files, the output of _b_g_g_e_n, etc.). They have no effect whatsoever on how GIF pictures or 8- bit greyscale images are displayed. -quick24 (Resource name: quick24 _b_o_o_l_e_a_n) Forces _x_v to use the 'quick' 24-bit to 8-bit conversion algorithm. This algorithm dithers the picture using a fixed set of colors that span the entire RGB colorspace. In versions of _x_v prior to 2.10, this was the default algorithm. It no longer is. -slow24 (Resource name: slow24 _b_o_o_l_e_a_n) Specifies that the 'slow' 24-bit to 8-bit conversion algorithm is to be used by the program. This algorithm uses a version of Heckbert's median cut algorithm to pick the 'best' colors on a per-image basis, and dithers with those. This is the current default conversion algorithm. Advantages: The -slow24 algorithm often produces better looking pictures than the -quick24 algorithm. Disadvantages: The -slow24 algorithm is about half the speed of the -quick24 algorithm. Also, since the colors are chosen on a per- image basis, it can't be used to display multiple images simultane- ously, as each image will almost certainly want a different set of 256 colors. The -quick24 algorithm, however, uses the same exact colors for all images, so it can display many images simultane- ously, without running out of colors. -best24 (Resource name: best24 _b_o_o_l_e_a_n) Forces _x_v to use the same algorithm used in the program _p_p_m_q_u_a_n_t, Rev: 2.10 39 xv(l) Feb 26, 1992 written by Jef Poskanzer. This algorithm also uses a version of Heckbert's median cut algorithm, but is capable of picking 'better' colors than the -slow24 algorithm, and it _d_o_e_s_n'_t dither. Advantages: Generally produces slightly better images than the -slow24 algorithm. Also, the images are undithered, so they look better when expanded. Disadvantages: _M_u_c_h slower than the -slow24 algorithm. Like, 5 to 10 times slower. The images produced aren't _t_h_a_t much better than those produced by the -slow24 algorithm. -noqcheck (Resource name: noqcheck _b_o_o_l_e_a_n) Turns off a 'quick check' that is normally made. Normally, before running either of the 24-bit to 8-bit conversion algorithms, _x_v determines whether the picture to be displayed has more than 256 unique colors in it. If the picture doesn't, it will treat the picture as an 8-bit colormapped image (i.e., GIF), and won't run either of the conversion algorithms. Advantages: The pictures will be displayed 'perfectly', whereas if they went through either of the conversion algorithms, they'd be dithered. Disadvantages: Often uses a lot of colors, which limits the ability to view multiple images at once. (See the -slow24 option above for further info about color sharing.) Section 9.6: Root Window Options _x_v has the ability to display images on the root window of an X display, rather than opening its own window (the default behavior). When using the root window, the program is somewhat limited, because the program cannot receive input events (key press and mouse clicks) from the root window. As a result, you cannot track pixel values, or crop, nor can you use keyboard commands while the mouse is in the root window. -root (Resource name: <none>) Directs _x_v to display images in the root window, instead of opening its own window. Exactly how the images will be displayed in the root window is determined by the setting of the -rmode option. -rmode _m_o_d_e (Resource name: rootMode _i_n_t_e_g_e_r) Determines how images are to be displayed on the root window, when -root has been specified. You can find the current list of 'modes' by using a mode value of '-1'. _X_V will complain, and show a list of valid modes. The current list at of the time of this writing is: 40 Rev: 2.10 Feb 26, 1992 xv(l) 0: tiling 1: integer tiling 2: mirrored tiling 3: integer mirrored tiling 4: centered tiling 5: centered on a solid background 6: centered on a 'warp' background 7: centered on a 'brick' background The default mode is '0'. See "Section 3.5: The Display Modes Menu" for a description of the different display modes. -noresetroot (Resource name: resetroot) Normally, when changing from root to window display mode, the root is set to the standard X crosshatch pattern. Using -noresetroot or setting resetroot to false will force the root to remain. This is useful when comparing between different tiled images. -rfg _c_o_l_o_r (Resource name: rootForeground _s_t_r_i_n_g) Sets the 'foreground' color used in some of the root display modes. -rbg _c_o_l_o_r (Resource name: rootBackground _s_t_r_i_n_g) Sets the 'background' color used in some of the root display modes. -max (Resource name: <none>) Makes _x_v automatically stretch the image to the full size of the screen. This is mostly useful when you want _x_v to display a back- ground. While you could just as well specify the dimensions of your display ('-geom 1152x900' for example), the -max option is display-independent. If you suddenly decide to start working on a 1280x1024 display (ferinstance) the same command will still work. Note: If you specify -max when you aren't using -root, the behavior is slightly different. The image will be made as large as possible while still preserving the normal aspect ratio. -maxpect (Resource name: <none>) Makes the image as large as possible while preserving the aspect ratio. -quit (Resource name: <none>) Makes _x_v display the (first) specified file and exit, without any user intervention. Since images displayed on the root window remain there until explicitly cleared, this is very useful for hav- ing _x_v display background images on the root window in some sort of start-up script. Needless to say, this is only useful if you are using -root. Rev: 2.10 41 xv(l) Feb 26, 1992 -clear (Resource name: <none>) Clears the root window of any extraneous _x_v images. Note: it is not necessary to do an 'xv -clear' before displaying another pic- ture in the root window. _x_v will detect that there's an old image in the root window and automatically clear it out (and free the associated colors). Section 9.7: Window Options _X_V currently consists of three main windows, plus one window for the actual image. These three windows (the _x_v _c_o_n_t_r_o_l_s window, the _x_v _i_n_f_o window, and the _x_v _c_o_l_o_r _e_d_i_t_o_r window) may be automatically mapped and positioned when the program starts. -cmap (Resource name: ctrlMap _b_o_o_l_e_a_n) Maps the _x_v _c_o_n_t_r_o_l_s window. -cgeom _g_e_o_m (Resource name: ctrlGeometry _s_t_r_i_n_g) Sets the initial geometry of the _x_v _c_o_n_t_r_o_l_s window. Note: only the position information is used. The window is of fixed size. -imap (Resource name: infoMap _b_o_o_l_e_a_n) Maps the _x_v _i_n_f_o window. -igeom _g_e_o_m (Resource name: infoGeometry _s_t_r_i_n_g) Sets the initial geometry of the _x_v _i_n_f_o window. Note: only the position information is used. The window is of fixed size. -cemap (Resource name: ceditMap _b_o_o_l_e_a_n) Maps the _x_v _c_o_l_o_r _e_d_i_t_o_r window. -cegeom _g_e_o_m (Resource name: ceditGeometry _s_t_r_i_n_g) Sets the initial geometry of the _x_v _c_o_l_o_r _e_d_i_t_o_r window. Note: only the position information is used. The window is of fixed size. -nopos (Resource name: nopos _b_o_o_l_e_a_n) Turns off the 'default' positioning of the various _x_v windows. Every time you open a window, you will be asked to position it. (Assuming your window manager asks you such things. _m_w_m, for instance doesn't seem to ask) 42 Rev: 2.10 Feb 26, 1992 xv(l) Section 9.8: Miscellaneous Options -mono (Resource name: mono _b_o_o_l_e_a_n) Forces the image to be displayed as a greyscale. This is most use- ful when you are using certain greyscale X displays. While _x_v attempts to determine if it's running on a greyscale display, many X displays lie, and claim to be able to do color. (This is often because they have color graphics boards hooked up to b/w monitors. The computer, of course, has no way of knowing what type of monitor is attached.) On these displays, if you don't specify -mono, what you will see is a greyscale representation of one of the RGB out- puts of the system. (For example, you'll see the 'red' output on our greyscale Sun 3/60s.) The -mono option corrects this behavior. -white _c_o_l_o_r (Resource name: white _s_t_r_i_n_g) Specifies the 'white' color used when the picture is b/w stippled. (When '-ncols 0' has been specified.) -black _c_o_l_o_r (Resource name: black _s_t_r_i_n_g) Specifies the 'black' color used when the picture is b/w stippled. (When '-ncols 0' has been specified.) Try something like: 'xv -ncols 0 -bl red -wh yellow <filename>' for some interesting, late-'60s-style psychodelia effects. -wait _s_e_c_s (Resource name: <none>) Turns on a 'slide-show' feature. Normally, if you specify multiple input files, _x_v will display the first one, and wait for you to give the Next command (or whatever). The -wait option makes _x_v wait the specified number of seconds, and then go on to the next picture, without any user intervention. The program still accepts commands, so it's possible to 'abort' the current picture without waiting the full specified time by using the Next command. -wloop (Resource name: <none>) Normally, when running a slide-show with the -wait option, _x_v will terminate after displaying the last image. If you also specify the -wloop option, the program will loop back to the first image and continue the slide-show until the user issues the Quit command. -rgb (Resource name: hsvMode _b_o_o_l_e_a_n) Specifies that, by default, the colormap editing dials in the _x_v _c_o_l_o_r _e_d_i_t_o_r window should be in RGB mode. This is the normal default behavior. -hsv (Resource name: hsvMode _b_o_o_l_e_a_n) Rev: 2.10 43 xv(l) Feb 26, 1992 Specifies that, by default, the colormap editing dials in the _x_v _c_o_l_o_r _e_d_i_t_o_r window should be in HSV mode. -dither (Resouce name: autoDither _b_o_o_l_e_a_n) When specified, tells _x_v to automatically issue a Dither command whenever an image is first displayed. Useful on displays with lim- ited color capabilities (4-bit and 6-bit displays.) -smooth (Resource name: autoSmooth _b_o_o_l_e_a_n) When specified, tells _x_v to automatically issue a Smooth command whenever an image is first displayed. This is useful when you are using one of the image sizing options (such as '-expand' or '- max'). -crop (Resource name: autoCrop _b_o_o_l_e_a_n) When specified, tells _x_v to automatically issue an AutoCrop command whenever an image is first displayed. -visual _v_i_s_t_y_p_e (Resource name: visual _s_t_r_i_n_g) Normally, _x_v uses the default visual model provided by your X server. You can override this by explicitly selecting a visual to use. Valid types are _S_t_a_t_i_c_G_r_a_y, _S_t_a_t_i_c_C_o_l_o_r, _T_r_u_e_C_o_l_o_r, _G_r_a_y_S_- _c_a_l_e, _P_s_e_u_d_o_C_o_l_o_r, and _D_i_r_e_c_t_C_o_l_o_r. Not all of these are necessarily provided on any given X display. Run _x_d_p_y_i_n_f_o on your display to find out what visual types are supported. -cursor _c_u_r_s (Resource name: cursor _i_n_t_e_g_e_r) Specifies an alternate cursor to use in the image window (instead of the normal 'cross' cursor). curs values are obtained by finding the character number of a cursor you like in the 'cursor' font. (Run 'xfd -fn cursor' to display the cursor font.) For example, a curs value of '56' corresponds to the (singularly useless) 'Gumby' cursor. -keeparound (Resource name: keepAround _b_o_o_l_e_a_n) The '-keeparound' option is now poorly named, as I've changed the default behavior. Now, if you Delete the last file in the _x_v _c_o_n_- _t_r_o_l_s list, nothing unexpected will happen. If you specify the '- keeparound' option, which toggles the '-keeparound' flag off, the program will automatically exit as a convenience. It should prob- ably be renamed '-goaway' or something... -2xlimit (Resource name: 2xlimit _b_o_o_l_e_a_n) By default, _x_v prevents the image window from ever getting larger than the screen. Unfortunately, because of this, if you load an image that is larger than your screen, the image will be shrunk 44 Rev: 2.10 Feb 26, 1992 xv(l) until it fits on your screen. Some folks find this undesirable behavior. Specifying the -2xlimit option doubles the size limita- tions. The image window will be kept from getting larger than 2x the width and height of your screen. Just in case you're wondering why there's any size limitations: it's fairly easy to accidentally ask for a huge image to be gen- erated. Simply crop a section of the image, zoom so you can see the individual pixels, and uncrop. If there were no size limita- tions, the (expanded many times) image could be huge, and might crash your X server. At the very least, it would take a long period of time, and freeze your X server during part of it. Gen- erally undesirable behavior. -nolimits (Resource name: nolimites _b_o_o_l_e_a_n) For the truly daring, this turns off all limitations on the maximum size of an image window. (Well, there's still an X-imposed maximum size of 64k by 64k, but that really shouldn't be a problem.) Warn- ing: as mentioned above, it is fairly easy to accidentally gen- erate a huge image when you do an UnCrop command, and you may well crash _x_v, your X server, the host machine, or all three. Use At Your Own Risk!!! -rv (Resource name: reverse) Makes _x_v display a 'negative' of the loaded image. White becomes black, and black becomes white. Color images will have 'interest- ing' effects, as the RGB components are individually reversed. For example, _r_e_d (255,0,0) will become _c_y_a_n (0,255,255), _y_e_l_l_o_w will become _b_l_u_e, and so on. -DEBUG _l_e_v_e_l (Resource name: <none>) Turns on some debugging information. You shouldn't need this. If everything worked perfectly, I wouldn't need this either. -browse (Resource name: browseMode _b_o_o_l_e_a_n) Prevents the _x_v _l_o_a_d window from being closed whenever you success- fully load a file. This makes 'browsing' a directory somewhat more pleasant. -nostat (Resource name: nostat _b_o_o_l_e_a_n) Turns off the stat() call is is performed for each file whenever you change directories in the _x_v _l_o_a_d and _x_v _s_a_v_e windows. This is useful if you're on a machine with lots of remote files mounted on it, and you find the directory switching to be too slow. -loadclear (Resource name: clearOnLoad _b_o_o_l_e_a_n) If you were on a PseudoColor display, _x_v used to automatically clear the image window (or the root window, if you were in a root Rev: 2.10 45 xv(l) Feb 26, 1992 mode), whenever you loaded a new image. This was to prevent the potentially annoying/confusing 'rainbow' effect that happens when colormap entries are freed and reallocated with different colors. Ths has changed. By default, _x_v no longer clears the image/root window. This is for two reasons: I've decided that the rainbow effect is semi-entertaining, in that it gives you something to look at while the next image is being loaded. Secondly, if you are viewing a series of images that have the same colors in them, it's possible for _x_v to animate them (by using the '-wait' command line option), albeit no faster than one frame every 1-2 seconds. For example, you can go get the satellite radar images from vmd.cso.uiuc.edu (in the directory 'wx'), run 'xv -wait 0 -wloop SA*', and voila! Just like the evening news! - Specifying '-' all by itself tells _x_v to take its input from stdin, rather than from a file. This lets you put _x_v on the end of a Un*x pipe. Section 9.9: Color Editor Resources You can set default values for all of the HSV and RGB modification con- trols in the _x_v _c_o_l_o_r _e_d_i_t_o_r window via X resources. The easiest way to explain this is with an example. o+ Start _x_v and put it in the background by typing 'xv &'. o+ Type the command 'cat >foo' in an active _x_t_e_r_m window o+ Bring the _x_v _c_o_l_o_r _e_d_i_t_o_r window up. o+ Issue the Cut Resources command. o+ Click your _M_i_d_d_l_e mouse button in the _x_t_e_r_m window. A set of resource lines describing the current state of the _x_v _c_o_l_o_r _e_d_i_t_o_r controls will be 'pasted' into the window. o+ You could type '<ctrl-D>' in the _x_t_e_r_m to complete the cat command, edit this file, and put it in your .Xdefaults/.Xresources file. The lines generated by Cut Resources will look like the following: xv.default.huemap1: 330 30 CW 330 30 CW xv.default.huemap2: 30 90 CW 30 90 CW xv.default.huemap3: 90 150 CW 90 150 CW xv.default.huemap4: 150 210 CW 150 210 CW xv.default.huemap5: 210 270 CW 210 270 CW xv.default.huemap6: 270 330 CW 270 330 CW xv.default.whtmap: 0 0 1 xv.default.satval: 0 xv.default.igraf: S 4 : 0,0 : 64,64 : 192,192 : 254,254 46 Rev: 2.10 Feb 26, 1992 xv(l) xv.default.rgraf: S 4 : 0,0 : 64,64 : 192,192 : 254,254 xv.default.ggraf: S 4 : 0,0 : 64,64 : 192,192 : 254,254 xv.default.bgraf: S 4 : 0,0 : 64,64 : 192,192 : 254,254 These lines completely describe one state of the _x_v _c_o_l_o_r _e_d_i_t_o_r con- trols. There are five different states that you can specify via X resources. The 'default' state (as shown) holds the settings used when- ever the program is first started, and whenever the Reset command is used. You can also store settings in one of the four _x_v presets (accessed via the '1'-'4' buttons in the _x_v _c_o_l_o_r _e_d_i_t_o_r) by changing the string 'default' in the above lines to 'preset1', 'preset2', 'preset3', or 'preset4' respectively. There are four types of resource described in these lines: huemap, whtmap, satval, and graf. Section 9.9.1: Huemap Resources The huemap resources describe the state of the hue remapping dials. There are six huemap resources per state of the _x_v _c_o_l_o_r _e_d_i_t_o_r. These huemap resources are numbered 'huemap1', 'huemap2', ... 'huemap6', and correspond to the '1'-'6' radio buttons under the hue remapping dials. Each huemap resources takes six parameters: 1. The 'starting' angle of the From range, in degrees (integer). 2. The 'ending' angle of the From range, in degrees (integer). 3. The direction of the From range. Either 'cw' (clockwise) or 'ccw' (counter-clockwise). 4. The 'starting' angle of the To range, in degrees (integer). 5. The 'ending' angle of the To range, in degrees (integer). 6. The direction of the To range. Either 'cw' or 'ccw'. Section 9.9.2: Whtmap Resources The whtmap resource describes the state of the white remapping control. There is one whtmap resource per state of the _x_v _c_o_l_o_r _e_d_i_t_o_r controls. The whtmap resource takes three parameters: 1. The hue to remap 'white' to, in degrees (integer). 2. The saturation to give to the remapped 'white', in percent (integer). 3. A boolean specifying whether the white remapping control is enabled. If '1', the control is enabled. If '0', the control is disabled. Rev: 2.10 47 xv(l) Feb 26, 1992 Section 9.9.3: Satval Resource The satval resource describes the value of the Saturation dial. There is one satval resource per state. The satval resource takes a single integer value, in the range +/-100, which specifies how much to add or subtract to overall image color saturation. Section 9.9.4: Graf Resources The graf resources describe the state of the four 'graph' windows in the _x_v _c_o_l_o_r _e_d_i_t_o_r window (Intensity, Red, Green, and Blue). The graf resources can be in one of two formats, 'gamma' and 'spline/line'. In 'gamma' format, the graf resource takes two parameters: 1. The letter 'G', specifying 'gamma' mode 2. A single floating point number specifying the gamma value. In 'spline/line' mode, the graf resource takes a variable number of parameters: 1. The letter 'S' specifying 'spline' mode, or the letter 'L' specifying 'line' mode. 2. An integer number indicating the number of handles (control points) that this graph window will have. (Must be in the range 2-16, inclusive.) 3. For each handle, there will be a ':', and the x and y positions of the handle, separated by a comma. The x and y positions can be in the range 0-255 inclusive. Section 9.9.5: Other Resources Also, there are the boolean resources 'autoApply', 'displayMods', and 'autoReset', which control the initial settings of the three checkboxes in the _x_v _c_o_l_o_r _e_d_i_t_o_r window. There are also boolean resources 'saveNormal', 'pspreview', and 'pscompress' which control the initial settings of the checkboxes in the _x_v _s_a_v_e and _x_v _p_o_s_t_s_c_r_i_p_t windows. 48 Rev: 2.10 Feb 26, 1992 xv(l) LIMITATIONS _x_v will NOT work on displays that aren't 1-, 2-, 4-, 6-, 8-, 16- 24-, or 32-bits deep. Luckily, that should still cover nearly every display out there. It may not work on certain 6- or 24-bit displays. It also only displays the first image in GIF files that have multiple images in them. As for PM pictures, this program only displays 1-plane PM_I pictures, or 1-, 3-, or 4-plane PM_C pictures. PM FORMAT The PM format is a file format that we use at the GRASP Lab for our image processing work. If you aren't at Penn, you are unlikely to ever run into a PM-format file, so don't worry about it. Please ignore all references to PM. The 4-, 6-, 16-, 24-, and 32-bit code has not been extensively tested. (A 4-bit MicroVax GPX system, a 6-bit HP 9000/320, a 16-bit Sony 3710, and a 24-bit HP 9000/350, respectively. The 32-bit code hasn't actually been tested at all.) You won't be able to do '-ncols 0' on a 6-, 16-, 24-, or 32-bit display, not that you should want to. AUTHORS John Bradley - bradley@cis.upenn.edu GIF reading code based on gif2ras.c, by Patrick J. Naughton (naughton@wind.sun.com) GIF writing code essentially unchanged from code written by Michael Maudlin (mlm@cs.cmu.edu). SUN Rasterfile i/o code written by Dave Heath (heath@cs.jhu.edu) JPEG interface code written by Markus Baur (s_baur@iravcl.ira.uka.de) JPEG i/o code provided by the Independent JPEG Group. TIFF i/o code and interface code written by Sam Leffler (sam@sgi.com) Portions of 'ppmquant' snarfed for the '-best24' algorithm. _p_p_m_q_u_a_n_t (and the rest of the _p_b_m_p_l_u_s package) was written by Jef Poskanzer. (jef@well.sf.ca.us) fsQuick code written and supplied by David B. Rosen (rosen@cns.bu.edu). This code is a very fast implementation of Floyd-Steinberg dithering for 1-bit b/w displays. Rev: 2.10 49